% html: Beginning of file: `install.html'
%  Installing Go 

\chapter{Install Go}
\label{chap:goinstall}

\section{Introduction}


Go is an open source project, distributed under a
BSD-style license.
This document explains how to check out the sources,
build them on your own machine, and run them.

There are two distinct ways to experiment with Go.
This document focuses on the \texttt{gc} Go
compiler and tools (\texttt{6g}, \texttt{8g} etc.).
For information on how to use \texttt{gccgo}, a more traditional
compiler using the GCC back end, see
Setting up and using gccgo.

\section{Environment variables}


The Go compilation environment depends on three environment
variables that you should set in your \texttt{.bashrc} or equivalent,
plus one optional variable:
\begin{verbatim}
  [me@machine ~]$ tail -5  .bashrc
  GOROOT=''$HOME/go''
  GOOS=''linux''
  GOARCH=''386''
  GOBIN=''$HOME/bin''
  export GOROOT GOOS GOARCH GOBIN
  [me@machine ~]$
\end{verbatim}
\begin{description}
\item[\texttt{\$GOROOT}] 
The root of the Go tree.  Typically this is \texttt{\$HOME/go}
	but it can be any directory.
\item[\texttt{\$GOOS} and \texttt{\$GOARCH}] 
	The name of the target operating system and compilation architecture.
        Choices for \texttt{\$GOOS} are \texttt{linux},
        \texttt{darwin} (Mac OS X 10.5 or 10.6),
        and \texttt{nacl} (Native Client, an incomplete port).
        Choices for \texttt{\$GOARCH} are \texttt{amd64} (64-bit x86, the most mature port),
        \texttt{386} (32-bit x86), and
        \texttt{arm} (32-bit ARM, an incomplete port).
        The valid combinations are
        \texttt{linux}/\texttt{amd64},
        \texttt{linux}/\texttt{arm},
        \texttt{linux}/\texttt{386},
        \texttt{darwin}/\texttt{amd64},
        \texttt{darwin}/\texttt{386},
        and
        \texttt{nacl}/\texttt{386}.
\item[\texttt{\$GOBIN} (optional)] 
	The location where binaries will be installed.
        If you set \texttt{\$GOBIN}, you need to ensure that it
        is in your \texttt{\$PATH} so that newly built Go-specific
        command such as the compiler can be found during the build.
        The default, \texttt{\$HOME/bin}, may already be in your \texttt{\$PATH}.
\end{description}

Note that \texttt{\$GOARCH} and \texttt{\$GOOS} identify the
\emph{target} environment, not the environment you are running on.
In effect, you are always cross-compiling.

After setting these variables in your \texttt{.bashrc}, double-check them by
listing your environment.
\begin{verbatim} 
$ env | grep '^GO'
\end{verbatim}

\section{Ports}


Go compilers support two operating systems (Linux, Mac OS X) and
three instruction sets.
The versions for Linux and Mac are equally capable except that the ARM port
does not run on OS X (yet).

There are important differences in the quality of the compilers for the different
architectures.
\begin{description}
\item[	\texttt{amd64} (a.k.a. \texttt{x86-64}); \texttt{6g,6l,6c,6a}] 
	The most mature implementation.  The compiler has an effective optimizer
        (registerizer) and generates good code (although \texttt{gccgo}
	can do noticeably better sometimes).
\item[	\texttt{386} (a.k.a. \texttt{x86} or \texttt{x86-32}); \texttt{8g,8l,8c,8a}] 
	Comparable to the \texttt{amd64} port. Not as well soaked but
        should be nearly as solid.
\item[	\texttt{arm} (a.k.a. \texttt{ARM}); \texttt{5g,5l,5c,5a}] 
	It's got a couple of outstanding bugs but is improving. Tested against QEMU
        and an android phone.
\end{description}

Except for things like low-level operating system interface code, the runtime
support is the same in all ports and includes a mark-and-sweep garbage collector
(a fancier one is in the works), efficient array and string slicing,
support for segmented stacks, and a strong goroutine implementation.

See the separate \texttt{gccgo} document
for details about that compiler and environment.

\section{Fetch the repository}


If you do not have Mercurial installed (you do not have an \texttt{hg} command),
this command:
\begin{verbatim} 
$ sudo easy_install mercurial
\end{verbatim}

works on most systems.
If that fails, visit the Mercurial Download\footnote{See URL http://mercurial.selenic.com/wiki/Download} page.

Make sure the \texttt{\$GOROOT} directory does not exist or is empty.
Then check out the repository:
\begin{verbatim} 
$ hg clone -r release https://go.googlecode.com/hg/ $GOROOT
\end{verbatim}

\section{Install Go}


The Go tool chain is written in C.  To build it, you need
to have  GCC, the standard C libraries, and the parser generator Bison
installed.  On OS X, they can be installed as part of Xcode\footnote{See URL http://developer.apple.com/TOOLS/Xcode/}.
On Linux, 
\begin{verbatim} 
$ sudo apt-get install bison gcc libc6-dev
\end{verbatim}

(or the equivalent on your Linux distribution).

To build the Go distribution, make sure \texttt{\$GOBIN}
(or \texttt{\$HOME/bin} if \texttt{\$GOBIN} is not set)
is in your \texttt{\$PATH} and then run
\begin{verbatim} 
$ cd $GOROOT/src
$ ./all.bash
\end{verbatim}

If \texttt{all.bash} goes well, it will finish by printing
\begin{verbatim} 
--- cd ../test
N known bugs; 0 unexpected bugs
\end{verbatim}

where \textsl{N} is a number that varies from release to release.

\section{Writing programs}


Given a file \texttt{file.go}, compile it using
\begin{verbatim} 
$ 6g file.go
\end{verbatim}

\texttt{6g} is the Go compiler for \texttt{amd64}; it will write the output
in \texttt{file.6}. The \&lsquo;\texttt{6}\&rsquo; identifies
files for the \texttt{amd64} architecture.
The identifier letters for \texttt{386} and \texttt{arm}
are \&lsquo;\texttt{8}\&rsquo; and \&lsquo;\texttt{5}\&rsquo;.
That is, if you were compiling for \texttt{386}, you would use
\texttt{8g} and the output would be named \texttt{file.8}.

To link the file, use
\begin{verbatim} 
$ 6l file.6
\end{verbatim}

and to run it
\begin{verbatim} 
$ ./6.out
\end{verbatim}

A complete example:
\begin{verbatim} 
$ cat >hello.go <<EOF
package main

import "fmt"

func main() {
	fmt.Printf("hello, world\n")
}
EOF
$ 6g hello.go
$ 6l hello.6
$ ./6.out
hello, world
$
\end{verbatim}

There is no need to list \texttt{hello.6}'s package dependencies
(in this case, package \texttt{fmt}) on the \texttt{6l}
command line.
The linker learns about them by reading \texttt{hello.6}.

To build more complicated programs, you will probably
want to use a
\texttt{Makefile}.
There are examples in places like
\texttt{\$GOROOT/src/cmd/godoc/Makefile}
and \texttt{\$GOROOT/src/pkg/*/Makefile}.

Following is a simple Makefile for above example.

\begin{verbatim}
[me@machine helloworld]$ ls -lrt
total 1160
-rw-rw-r-- 1 tjyang tjyang     71 2009-11-12 00:26 hello.go
-rw-rw-r-- 1 tjyang tjyang   5161 2009-11-12 00:26 hello.8
-rwxrwxr-x 1 tjyang tjyang 581404 2009-11-12 00:26 8.out
-rw-rw-r-- 1 tjyang tjyang     60 2009-11-17 17:24 Makefile
-rwxrwxr-x 1 tjyang tjyang 581404 2009-11-17 17:24 hello.out
[me@machine helloworld]$ cat Makefile
all: hello.out

%.8: %.go
        8g $<

%.out: %.8
        8l -o $@ $<
[me@machine helloworld]\$ ./hello.out
hello, world

\end{verbatim}

The document about contributing to the Go project gives more detail about
the process of building and testing Go programs.


\section{Community resources}


For real-time help, there may be users or developers on
\texttt{\#go-nuts} on the Freenode\footnote{See URL http://freenode.net/} IRC server.

The official mailing list for discussion of the Go language is
Go Nuts\footnote{See URL http://groups.google.com/group/golang-nuts}.

Bugs can be reported using the Go issue tracker\footnote{See URL http://code.google.com/p/go/issues/list}.

For those who wish to keep up with development,
there is another mailing list, golang-checkins\footnote{See URL http://groups.google.com/group/golang-checkins},
that receives a message summarizing each checkin to the Go repository.
% html: End of file: `install.html'
